asyncapi: '3.0.0'
info:
  title: Authentication Service
  version: '1'
  description: |
    AsyncAPI definition for authentication-related operations in the banking system.
    This API enables device authentication, session management, and logout operations.

    :::warning
    Please note that all the *Commands* and *Events* are wrapped into *Envelope* before being dispatched via Channels.
    :::

    Specific properties that are present in the metadata section of the envelope varied per message.
    The list of required metadata properties is provided in the header's documentation of the corresponding message.

    See this <Link href="/docs/index.html">page</Link> for the more details on the *Envelope* structure and other cross-cutting concerns.

defaultContentType: application/avro

servers:
  kafka:
    host: localhost:9092
    protocol: kafka

operations:
  # events
  DeviceLoggedOut:
    action: send
    channel:
      $ref: '#/channels/authentication.event.device-logged-out'

  DeviceRemoved:
    action: send
    channel:
      $ref: '#/channels/authentication.event.device-removed'

  UserDeviceBiometricsDisabled:
    action: send
    channel:
      $ref: '#/channels/authentication.event.user-device-biometrics-disabled'

  UserDevicePasscodeDisabled:
    action: send
    channel:
      $ref: '#/channels/authentication.event.user-device-passcode-disabled'

  UserDeactivated:
    action: send
    channel:
      $ref: '#/channels/authentication.event.user-deactivated'

  UserActivated:
    action: send
    channel:
      $ref: '#/channels/authentication.event.user-activated'

  UserLoggedIn:
    action: send
    channel:
      $ref: '#/channels/authentication.event.user-logged-in'

  SensitiveOperationSigned:
    action: send
    channel:
      $ref: '#/channels/signatures.event.sensitive-operation-signed'

channels:
  authentication.event.device-logged-out:
    address: authentication.event.device-logged-out
    x-eventcatalog-role: provider
    messages:
      DeviceLoggedOutEvent:
        $ref: '#/components/messages/DeviceLoggedOutEvent'

  authentication.event.device-removed:
    address: authentication.event.device-removed
    x-eventcatalog-role: provider
    messages:
      DeviceRemovedEvent:
        $ref: '#/components/messages/DeviceRemovedEvent'

  authentication.event.user-device-biometrics-disabled:
    address: authentication.event.user-device-biometrics-disabled
    x-eventcatalog-role: provider
    messages:
      UserDeviceBiometricsDisabledEvent:
        $ref: '#/components/messages/UserDeviceBiometricsDisabledEvent'

  authentication.event.user-device-passcode-disabled:
    address: authentication.event.user-device-passcode-disabled
    x-eventcatalog-role: provider
    messages:
      UserDevicePasscodeDisabledEvent:
        $ref: '#/components/messages/UserDevicePasscodeDisabledEvent'

  authentication.event.user-deactivated:
    address: authentication.event.user-deactivated
    x-eventcatalog-role: provider
    messages:
      UserDeactivatedEvent:
        $ref: '#/components/messages/UserDeactivatedEvent'

  authentication.event.user-activated:
    address: authentication.event.user-activated
    x-eventcatalog-role: provider
    messages:
      UserActivatedEvent:
        $ref: '#/components/messages/UserActivatedEvent'

  authentication.event.user-logged-in:
    address: authentication.event.user-logged-in
    x-eventcatalog-role: provider
    messages:
      UserLoggedInEvent:
        $ref: '#/components/messages/UserLoggedInEvent'

  signatures.event.sensitive-operation-signed:
    address: signatures.event.sensitive-operation-signed
    x-eventcatalog-role: provider
    messages:
      SensitiveOperationSigned:
        $ref: '#/components/messages/SensitiveOperationSigned'

components:
  messages:
    # Events
    DeviceLoggedOutEvent:
      name: DeviceLoggedOut
      title: Device Logged Out Event
      summary: Event emitted when a user's device has logged out
      description: Published when a user's device has been logged out of the system, either by user action or system action
      x-eventcatalog-message-type: event
      payload:
        $ref: '#/components/schemas/DeviceLoggedOut'

    DeviceRemovedEvent:
      name: DeviceRemoved
      title: Device Removed Event
      summary: Event emitted when a device is removed from a user's account
      description: Published when a device is removed from a user's account, either by user action or system action
      x-eventcatalog-message-type: event
      payload:
        $ref: '#/components/schemas/DeviceRemoved'

    UserDeviceBiometricsDisabledEvent:
      name: UserDeviceBiometricsDisabled
      title: User Device Biometrics Disabled Event
      summary: Event emitted when a user's device biometrics has been disabled
      description: Published when biometrics is disabled on a user's device by staff action
      x-eventcatalog-message-type: event
      payload:
        $ref: '#/components/schemas/UserDeviceBiometricsDisabled'

    UserDevicePasscodeDisabledEvent:
      name: UserDevicePasscodeDisabled
      title: User Device Passcode Disabled Event
      summary: Event emitted when a user's device passcode has been disabled
      description: Published when passcode is disabled on a user's device by staff action
      x-eventcatalog-message-type: event
      payload:
        $ref: '#/components/schemas/UserDevicePasscodeDisabled'

    UserDeactivatedEvent:
      name: UserDeactivated
      title: User Deactivated Event
      summary: Event emitted when a user is deactivated
      description: Published when a user is deactivated by a staff
      x-eventcatalog-message-type: event
      payload:
        $ref: '#/components/schemas/UserDeactivated'

    UserActivatedEvent:
      name: UserActivated
      title: User Activated Event
      summary: Event emitted when a user is activated
      description: Published when a user is activated by a staff
      x-eventcatalog-message-type: event
      payload:
        $ref: '#/components/schemas/UserActivated'

    UserLoggedInEvent:
      name: UserLoggedIn
      title: User Logged In Event
      summary: Event emitted when a user successfully logs in
      description: Published by the authentication orchestrator after session confirmation, including the parties associated with the authenticated user
      x-eventcatalog-message-type: event
      payload:
        $ref: '#/components/schemas/UserLoggedIn'

    SensitiveOperationSigned:
      name: SensitiveOperationSigned
      title: Sensitive Operation Signed Event
      summary: Event emitted when sensitive operation is signed
      description: Published whenever a challenge for an operation requiring a signature is completed
      x-eventcatalog-message-type: event
      payload:
        $ref: '#/components/schemas/SensitiveOperationSigned'

  schemas:
    AccountUsage:
      type: string
      description: Identifies whether the party is an individual or an organisation
      enum:
        - ORGANISATION
        - INDIVIDUAL

    OriginPartyDomain:
      type: string
      description: Domain for which the origin system party is used
      enum:
        - PARTIES
        - ACCOUNTS

    OriginParty:
      type: object
      description: Qualified origin-system party reference attached to a party
      required:
        - qualifiedOriginPartyId
        - originPartyDomain
      properties:
        qualifiedOriginPartyId:
          type: string
          format: uri
          description: Qualified identifier of the party in the source system
        originPartyDomain:
          $ref: '#/components/schemas/OriginPartyDomain'

    PartyDetails:
      type: object
      description: Party information included in the login event
      required:
        - partyId
        - usage
        - originParties
      properties:
        partyId:
          type: string
          description: Internal identifier of the party
        usage:
          $ref: '#/components/schemas/AccountUsage'
        originParties:
          type: array
          description: Origin-system references linked to the party
          items:
            $ref: '#/components/schemas/OriginParty'

    UserLoggedIn:
      allOf:
        - type: object
          required:
            - id
          properties:
            id:
              type: string
              description: Event identifier. In the current producer implementation this is the confirmed session id
        - type: object
          description: Event published when a user successfully logs into the system
          required:
            - partyDetails
          properties:
            partyDetails:
              type: array
              description: Parties associated with the authenticated user at login time
              items:
                $ref: '#/components/schemas/PartyDetails'

    SensitiveOperationSigned:
      allOf:
        - $ref: '#/components/schemas/Event'
        - type: object
          description: Event published when a sensitive operation is signed
          required:
            - source
            - timestamp
            - signature
          properties:
            source:
              type: string
              description: Source requiring the signature (e.g. the path of an API request requiring the signature challenge to be completed).
            timestamp:
              type: string
              format: date-time
              description: Timestamp when signature was verified.
            signature:
              type: string
              description: Base64 encoded `p7m` signature container.

    Event:
      description: Base type for all events in the system
      allOf:
        - $ref: '#/components/schemas/Message'

    Message:
      type: object
      description: Base message type that all commands and events inherit from
      required:
        - id
      properties:
        id:
          type: string
          description: Unique identifier for the message, typically a UUID
          default: UUID generated string

    DeviceLoggedOut:
      schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
      schema:
        $ref: './DeviceLoggedOut.avsc'

    DeviceRemoved:
      schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
      schema:
        $ref: './DeviceRemoved.avsc'

    UserDeviceBiometricsDisabled:
      schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
      schema:
        $ref: './UserDeviceBiometricsDisabled.avsc'

    UserDevicePasscodeDisabled:
      schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
      schema:
        $ref: './UserDevicePasscodeDisabled.avsc'

    UserDeactivated:
      schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
      schema:
        $ref: './UserDeactivated.avsc'

    UserActivated:
      schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
      schema:
        $ref: './UserActivated.avsc'